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ABSTRACT 

/;•  K  r  fp-  \~f 

' '  The  modules  documented  herein  are  designed  for  use  with  the  nonlinear 
programming  system  MINOS/AUGMENTED  when  implementing  algorithms  re¬ 
quiring  the  solution  of  sequences  of  similar  mathematical  programs.  Large-scale 
constrained  mathematical  programming  requires  the  use  of  special  data  struc¬ 
tures  which  make  in-core  problem  modification  difficult.  These  modules  allow 
in-core  modification  of  nonlinear  programs  without  knowledge  of  the  specialized 
data  structures  used  in  MINOS/AUGMENTED. 

The  modifications  addressed  by  these  modules  are:  modification  of  elements 
in  the  constraint  matrix,  linear  objective  or  right  hand  side;  modification  of 
bounds  on  individual  variables;  modification  of  the  nonlinear  functions;  and 
appending  columns  to  the  constraint  matrix.  The  user  specifies  the  flow  and 
nature  of  problem  modifications  via  a  Fortran  subroutine.  A  simple  example  of 
the  use  of  each  of  the  modules  is  presented. 

This  manual  supplements  Reports  SOL  77-9  and  SOL  80-14,  the  MINOS 
User’s  Guide  and  the  MINOS/AUGMENTED  User’s  Manual. 
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1.  OVERVIEW 

It  has  become  apparent  that  it  would  be  useful  to  hare  a  nonlinear  programming 
code  suitable  for  solving  a  sequence  of  mathematical  programs  of  the  following 
form;  at  the  ifc-th  step 


minimize  Fk(x)  -f-  ( ek)Tx 

subject  to  fk(x)  +  Akx  =  bk  (Pk) 

lk  <  x  <  u* 

where  lk,  u*,  c*  are  n  vectors,  bk  is  an  m  vector,  and  A*  is  an  to  by  n  matrix, 
and  where  Fk  and  fk  are  continuous  and  differentiable  over  the  feasible  region. 
Dantsig- Wolfe  Decomposition  [1]  for  large-scale  linear  programming  and  the 
Manne-Chao- Wilson  algorithm  for  solving  for  competitive  equilibria  [2]  are  two 
algorithms  that  require  solving  a  sequence  of  similar  mathematical  programs. 

The  author  has  created  a  set  of  four  subroutines  to  assist  the  implemen¬ 
tation  of  algorithms  involving  the  solution  of  sequences  of  mathematical  pro¬ 
grams  which  are  substantially  the  same.  Their  use  avoids  the  need  to  learn  the 
data  structures  involved  in  expressing  the  sparse  problem,  and  they  provide  a 
framework  for  the  efficient  implementation  of  such  algorithms. 

These  subroutines  are  available  on  the  MINOS  Distribution  Tape.  The  tape 
is  documented  in  Report  SOL  80-100. 

2.  ON  UNDERSTANDING  THIS  SYSTEM 

Modification  of  the  problem  Pk  to  express  Pfc+1  can  be  achieved  by  a  combina¬ 
tion  of: 

1.  modifying  the  bounds  lk  and  uk  ; 

2.  adding  constraints; 

3.  adding  columns  to  Ak ; 

4.  modifying  elements  of  Ak,  ek  and  &*;  and 

5.  modifying  the  nonlinear  functions  Fk  and  fk. 

Operation  2  is  implemented  as  a  combination  of  1  and  4  as  follows.  Declare 
a  free  row  and  input  elements  which  will  not  be  rejected  as  too  small  in  the 
original  matrix  A1.  (See  note  regarding  AIJTOL  in  §4.3.)  Note  that  a  free  row  is 
a  constraint  whose  corresponding  logical  variable  has  a  very  large  negative  lower 
bound,  and  a  very  large  positive  upper  bound.  Row  type  “IT  in  the  MPS  file 
corresponds  to  a  free  row.  (See  SOL  77-9.)  After  the  Jk-th  problem  is  solved, 
and  it  is  desired  to  add  the  row,  the  matrix  elements  are  individually  modified  to 
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create  the  proper  coefficients  and  right-hand-side.  The  final  step  which  completes 
the  addition  of  this  constraint  to  the  problem  is  the  modification  to  the  bounds 
of  the  logical  variable  associated  with  the  row  to  be  added. 

The  other  transformations  are  straight  forward.  The  reader  is  directed  to 
the  subroutine  specifications  found  later  in  this  report. 

Rule  to  remember — one  can  not  enlarge  or  change  the  “non-sero  pattern” 
in  a  column  once  it  has  been  added  to  the  problem. 


S.  ADDITIONAL  PROBLEM  SPECIFICATIONS 

The  problem  specifications,  or  SPECS  file,  is  fully  documented  in  SOL  77-9, 
and  this  information  is  supplements '  in  SOL  80-14.  A  list  of  the  additional 
keywords  useful  for  solving  sequences  of  mathematical  programs  follows  with  a 
short  explanation  of  each. 

Note:  The  syntax  for  the  SPECS  file  is  discussed  in  SOL  77-9. 


CYCLE  LIMIT  k  (default  lb  =  1) 

This  parameter  indicates  that  the  maximum  number  of  problems  to  be  solved 

is  k. 


CYCLE  PRINT  j  (default  j  =  1) 

This  parameter  controls  printing.  At  most,  the  last  j  solutions  will  be  output. 
After  returning  from  a  subroutine  call  to  MATMOD  which  returns  FINISH= 
.FALSE.,  the  system  checks  to  see  if  the  maximum  number  of  cycles  minus  the 
current  number  of  calls  to  MATMOD  is  less  than  j.  If  so,  then  the  next  solution  is 
printed.  After  a  call  to  MATMOD  which  returns  FINISH=.TRUE.,  if  the  solution 
from  the  previous  cycle  was  not  printed,  it  is  printed  now. 


CYCLE  TOLERANCE  t  (default  *  =0.0) 

The  value  t  is  passed  to  MATMOD  as  the  parameter  CNVTOL  for  use  in  a  user 
specified  convergence  test.  This  gives  one  the  facility  to  vary  the  convergence 
criterion  for  the  cycling  algorithm  without  recompiling  the  MATMOD  routine.  (See 
§4.1.) 

PHANTOM  C0LUMN8  k  (default  *  =  PHANTOM  ELEMENTS/ 10) 

This  parameter  specifies  the  expected  number  of  columns  to  be  added  beyond 
those  in  the  original  MPS  input  deck. 
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PHANTOM  ELEMENTS  k  (default  *  =  10  X  PHANTOM  COLUMNS) 

This  parameter  specifies  the  total  number  of  nonzero  elements  to  be  allocated 
to  the  "phantom  columns”  after  input  of  the  original  matrix.  It  should  include 
space  for  possible  linear  objective  entries. 


Note:  If  both  the  PHANTOM  COLUMNS  and  the  PHANTOM  ELEMEMT8  parameters  are 
not  specified,  both  will  be  set  to  0.  Also,  during  input  of  the  MPS  file,  it  may 
be  desirable  to  accept  "non- zero”  elements  of  A1  which  are  arbitrarily  small  in 
the  absolute  sense,  or  even  zero.  Normally  these  are  not  stored.  However,  one 
can  suppress  the  rejection  of  small  elements  by  manipulating  the  parameter  AI J 
TOLERANCE  (see  SOL  77-9).  Set  the  value  of  this  parameter  to  zero  to  accept 
arbitrarily  small  non-zero  values  as  "non-zeros” .  Set  the  value  of  this  parameter 
to  a  negative  number  to  accept  any  matrix  element  as  a  "non-zero”  regardless 
of  its  absolute  size.  (Remember,  one  can  not  change  the  "non-zero  pattern”  of 
a  column  once  it  has  become  part  of  the  current  problem.) 


4.  SUBROUTINE  DOCUMENTATION 

The  following  six  subroutines  provide  a  framework  for  problem  modification. 
MATMOD  is  provided  by  the  user,  and  MINOS  (the  subroutine)  may  be  modified  by 
the  user  if  necessary.  The  other  subroutines  are  to  be  called  where  needed  within 
MATMOD.  These  subroutines  are  available  on  the  MINOS  Distribution  Tape.  (See 
SOL  80-100.) 

4.1  SUBROUTINE  MATMOD 

This  subroutine  is  provided  by  the  user  to  direct  the  flow  and  nature  of  problem 
modifications.  The  constraint  matrix,  bounds,  linear  objective,  right-hand-side 
and/or  the  nonlinear  functions  of  the  problem  can  be  modified  within  MATMOD. 


Specification: 

SUBROUTINE  MATMOD (  NCYCLE.CNVT0L, FINISH, 

1  M, N, NR0YS , NC0LS , NE, NP1 , 

2  A,BL,BU,HA,KA, ID1 , ID2, 

3  PI.XL.XS.Z.MAXZ.LFREE  ) 

IMPLICIT  REAL*8(C-G,0-Z) 

REAL  A (NE) , BL (N) , BU (N) 

REAL*8  PI (NR0VS) . XL (NR0VS) , X8 (NC0LS) , Z (MAXZ) 

INTEGERS  HA(NE) 

INTEGER  KA(NPl) . ID1 (N) . ID2 (N) 
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LOGICAL  FINISH 

Declarations  of  variable  type  REAL*8  should  not  be  used  when  single  preci¬ 
sion  is  adequate;  e.g.  on  Burroughs  and  CDC  machines.  Similarly,  INTEGER*2 
should  be  replaced  by  INTEGER  when  not  available. 


Parameters: 

CNVTOL  (Input)  This  constant  is  input  from  the  SPECS  file  (see  page  3,  CYCLE 
TOLERANCE)  to  be  used  within  MATMOD  to  determine  "convergence”  of 
the  user’s  algorithm. 

FINISH  (Output)  This  logical  variable  is  used  to  signal  convergence  of  the  user’s 
algorithm.  Set  FINISH  =  .TRUE,  to  break  out  of  the  problem  solution 
loop  and  output  the  final  solution  according  to  the  SOLUTION  keyword 
in  the  SPECS  file.  After  FINISH  is  set  to  .  TRUE,  no  more  mathematical 
programs  are  solved.  FINISH  is  initialized  to  be  .FALSE,  in  MATMOD. 

NCYCLE  (Input)  This  variable  is  equal  to  (the  number  of  mathematical  programs 
solved)-!- 1.  For  example,  NCYCLE  is  1  on  the  first  entry  to  MATMOD  before 
any  mathematical  programs  have  been  solved. 

NCOLS  (Input)  The  number  of  columns  (excluding  logicals  and  the  right-hand- 
side)  in  the  problem.  Note  that  PHANTOM  COLUMNS  are  counted  in 
NCOLS. 

NROVS  (Input)  The  number  of  rows  in  the  problem,  including  the  linear  objec¬ 
tive,  if  it  exists. 

XL(*)  (Input)  The  solution  values  of  the  logical  (slack  or  artificial)  variables. 

X8(*)  (Input)  The  solution  values  of  the  structural  variables. 

PI  (*)  (Input)  The  dual  solution  to  the  mathematical  program. 

Others  (Input/Output)  Parameters  for  the  subroutines  called  by  MATMOD.  Note 
that  the  constraint  and  bound  data  lies  in  this  storage.  It  is  a  good 
idea  not  to  try  to  manipulate  this  storage  except  via  the  subroutines 
documented  herein. 


Note:  XL(*),  XS(*)  and  PI(*)  may  be  used  as  work  vectors  within  MATMOD. 
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For  some  applications  it  may  be  important  to  stop  solution  of  the  sequence 
of  mathematical  programs  if  the  previous  program  was  not  solved  as  intended. 
This  can  be  accomplished  by  testing  the  common  variable  IERR  in  common 
block  LPCOM.  If  the  value  of  this  variable  is  not  zero,  then  some  error  condition 
(e.g.,  infeasibility,  unboundedness,  too  many  iterations)  has  arisen  within  the 
MINOS/AUGMENTED  system.  In  general,  it  is  a  good  idea  to  declare  common 
block  LPCOM  in  MATMOD  (see  example)  and  insert  the  following  statement  as  the 
first  line  of  executable  code: 

IF  (IERR.NE.O)  STOP 


4.2  SUBROUTINE  MINOS 

This  subroutine,  provided  on  the  MINOS  distribution  tape,  is  fully  documented 
within  the  source  code.  Standard  MINOS/AUGMENTED  contains  subroutine 
MINOS  similar  to  the  one  documented  in  Report  SOL  77-31.  One  important 
enhancement  is  that  it  allows  for  a  “flying  start”,  wherein  the  basis,  superbasis, 
Lagrange  multiplier  estimates  and  reduced  Hessian  approximation  are  retained 
from  the  previous  problem,  Pk ,  to  provide  an  advanced  start  for  P*"*"1. 

If  all  problem  modifications  during  the  sequence  modify  only  the  nonlinear 
functions  based  on  the  values  of  the  nonlinear  variables,  then  standard  MINOS/ 
AUGMENTED  may  be  used  as  is,  and  subroutine  MATMOD  is  unnecessary.  (See 
§7  for  details.) 

If  problem  modifications  include  modifying  the  linear  constraints  or  bounds 
on  individual  variables,  and/or  if  the  nonlinear  functions  can  not  be  modified 
solely  on  the  basis  of  the  optimal  values  of  the  nonlinear  variables  for  the  previous 
problems,  then  a  special  version  of  subroutine  MINOS  should  be  used.  Files  13- 
15  of  the  tape  contain  this  special  version  of  subroutine  MINOS  along  with  the 
skeleton  of  MATMOD  and  the  modules  MKCOL,  MODBND  and  MODELM. 

Normally  neither  of  these  two  versions  of  subroutine  MINOS  will  be  changed. 
For  a  variety  of  reasons,  the  user  may  wish  to  suppress  the  flying  start  feature. 
This  can  be  accomplished  by  replacing  NCYCLE  by  1  in  the  call  to  subroutine 
DRIVER. 

4.3  SUBROUTINE  MKCOL 

This  subroutine  is  provided  to  facilitate  adding  columns  to  the  constraint  matrix 
within  MATMOD.  Given  the  vector  ACOL,  below,  store  the  elements  of  this  vector 
which  are  larger  than  AIJTOL,  in  the  absolute  sense,  in  A  and  HA.  Components 
smaller  than  AIJTOL  are  not  stored.  Effectively,  add  the  vector  corresponding  to 
ACOL,  as  a  new  column,  to  the  constraint  matrix.  The  bounds  corresponding  to 
the  new  column  are  set  to  the  default  values  for  structural  variables.  (See  SOL 
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77-9.)  Note  that  it  is  necessary  to  provide  for  PHANTOM  COLUMNS  if  this  subroutine 
is  used.  If  the  phantom  column  space  runs  out,  MKCOL  prints  a  message  to  that 
effect  and  flags  an  error  to  stop  solution  of  the  next  mathematical  program. 
Similarly,  if  the  new  column  has  no  components  larger  than  AIJTOL,  then  a 
message  is  printed  and  an  error  is  flagged. 


Specification: 

SUBROUTINE  MKCOL(  A. ACOL,BL,BU.HA,KA, LENCOL. N.NE.NP1  ) 
IMPLICIT  REAL*8(C-G,0-Z) 

INTEGERS  HA(NE) 

INTEGER  KA(NPl) 

REAL  A (NE) . ACOL (LENCOL) , BL (N) , BU (N) 


Parameters: 

ACOLC*)  (Input)  The  new  column  to  be  appended  to  Ak. 

LENCOL  (Input)  This  parameter  indicates  the  length  of  the  column  to  be  ap¬ 
pended  to  the  matrix.  Note  that  LENCOL  must  satisfy  LENCOL  <  NRQVS. 

Others  (Input/ Output)  Data  to  be  modified  via  this  subroutine. 


For  some  applications  it  may  be  useful  to  read  in  and  store  some  zeros  in 
the  original  matrix,  A1.  To  accomplish  this,  one  method  is  to  set  the  parameter 
“AIJ  TOLERANCE”  in  the  SPECS  file  to  a  negative  number.  However,  this  is  the 
same  tolerance  (AIJTOL)  used  to  filter  “zero”  elements  in  new  columns  by  MKCOL. 
Hence,  to  avoid  storing  all  elements  of  the  new  column  regardless  of  size,  the 
common  variable  AIJTOL  should  be  reset  within  MATMOD,  before  the  first  call  to 
MKCOL.  AIJTOL  is  located  in  common  block  MPSCOM.  This  is  illustrated  in  the 
example  of  MATMOD. 


4.4  SUBROUTINE  MODBND 

This  subroutine,  provided  for  the  user  to  call  within  MATMOD,  modifies  an  upper 
or  lower  bound  for  a  single  variable.  If  the  index  of  this  variable  is  zero,  or  too 
large  (bigger  than  N,  the  number  of  structural  -f-  1  -|-  the  number  of  logicals), 
then  an  error  message  is  printed  and  a  flag  is  set  to  halt  execution  of  the  present 
sequence  of  mathematical  programs. 

Note  that  both  structurals  and  logicals  have  upper  and  lower  bounds.  For 
each  type  of  inequality,  the  logicals  have  the  following  bound  structure: 
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<  /,  =  0  and  Ui  =  PLINFY; 

=  /,  =  0  and  Ui  =  0; 

>  li  =  -PLINFY  and  u,  =  0; 

free  /,•  =  -PLINFY  and  u,  =  PLINFY. 

PLINFY  is  a  very  large  number  (usually  1 . 0E+20)  and  is  used  to  specify  infinite 
bounds.  It  is  located  in  the  common  block  EPSCOM.  (All  common  blocks  are  listed 
in  the  source  code  of  subroutine  MIN08  for  reference.) 

Specification: 

SUBROUTINE  MODBNDC  IMOD. BVAL. BL.BU.N  ) 

IMPLICIT  REAL*8 (C-G , 0-Z) 

INTEGER  IMOD 

REAL  BL (N) , 3U (N) , BVAL 

Parameters: 

IMOD  (Input)  This  parameter  is  the  number  of  the  variable  whose  bound  is  to 
be  modified  with  a  possible  change  in  sign.  If  IMOD  is  negative  then  the 
lower  bound  will  be  changed;  IMOD  positive  indicates  the  upper  bound 
will  be  changed. 

BVAL  (Input)  This  parameter  is  the  new  value  of  the  bound  indicated  by 
IMOD. 

Others  (Input/Output)  Data  to  be  modified  via  this  subroutine. 

4.S  SUBROUTINE  MODELM 

This  subroutine,  provided  for  the  user  to  call  within  MATMOD,  resets  an  existing 
element  of  either  the  constraint  matrix,  the  linear  portion  of  the  objective 
function,  or  the  right-hand- side,  to  a  given  value.  The  effect  of  this  subroutine 
is  equivalent  to  setting  “A(I ,  J)  =  AVAL”. 

Note  that  the  linear  objective  and  right-hand-side  are  imbedded  in  Ak  as  a 
free  row  and  as  a  column  with  upper  and  loweT  bounds  both  equal  to  minus  one 
respectively. 

Specification: 

SUBROUTINE  MODELM (  A. I, J.AVAL.HA.KA.M.N.NE.NPl  ) 

IMPLICIT  REAL*8 (C-G , 0-2) 

INTEGERS  HA(NE) 

INTEGER  I.J.KA(NPl) 

REAL  A(NE) .AVAL 
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Parameters: 

I  (Input)  The  row  number  of  the  element  to  be  modified. 

J  (Input)  The  column  number  of  the  element  to  be  modified. 

AVAL  (Input)  The  new  value  for  the  element  in  row  I  and  column  J. 

Others  (Input/Output)  Data  to  be  modified  via  this  subroutine. 

Note:  There  must  already  exist  in  the  matrix  an  element  in  row  I  and  column  J 
before  this  subroutine  is  called.  If  not,  an  error  message  is  printed,  and  execution 
of  the  current  sequence  of  mathematical  programs  is  stopped. 

4.6  SUBROUTINE  NMSRCH 

This  subroutine  can  be  called  from  MATMOD  to  determine  the  index  of  a  variable 
with  a  given  name.  It  is  documented  in  SOL  77-31.  Since  the  phantom  column 
names  are  not  stored  in-core  until  after  P 1  has  been  solved,  a  call  to  NMSRCH 
to  find  the  index  of  a  phantom  column  via  its  name  will  not  succeed  until  that 
time.  Determining  the  index  of  a  phantom  column  is  better  accomplished  by 
computing  its  value  from  pointers  available  in  common.  (See  $5.) 

5.  ON  STORAGE  AND  INDICES 

Constraint  rows  and  objective  rows  of  the  matrix  are  indexed  in  the  order  that 
they  are  read  from  the  MPS  input  file.  Rows  with  no  elements  specified  will  be 
retained  and  indexed.  Variables  corresponding  to  columns  in  the  MPS  deck  are 
numbered  in  the  order  that  they  are  read.  A  column  with  no  elements  is  assigned 
a  zero  in  row  one.  (A  warning  message  will  be  printed  in  this  case  unless  the 
variable  is  specified  to  be  nonlinear.  In  any  case,  execution  continues.)  Phantom 
columns  come  afteT  the  original  columns  and  are  indexed  accordingly.  The  next 
“column”  in  the  A  file  is  the  right-hand-side  which  is  treated  as  a  fixed  variable. 
Finally  come  the  slack,  or  logical,  variables.  KRHS  in  the  common  block  LPCOM  is 
the  column  number  of  the  right-hand-side,  and  IOBJ  in  the  common  block  FXCOM 
is  the  row  number  of  the  linear  portion  of  the  objective  function.  (IOBJ  is  zero 
if  there  is  no  linear  objective.) 

Note  that  the  logical  variable  corresponding  to  the  objective  row  is  stored 
as  column  number  KRH8-|-I0BJ.  Similarly,  the  t-th  logical  variable  is  stored  in 
column  KRH8-}-*. 

6.  AN  EXAMPLE  OF  MATMOD 

The  following  example  illustrates  the  use  of  subroutines  MXCOL,  MODBND,  MODELM 
and  NMSRCH  within  a  user’s  version  of  MATMOD. 


onooooo 


§e 

1.  Solve  the  linear  program; 


An  Example  of  MATMOD 
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minimize  —  5*i  —  8x2  —  5*s  —  6*4  —  7*# 


subject  to 


■11  1  1  1  • 

'4' 

2  2-1-3  5 

6 

2  2  3  0  0 

X  < 

4 

-3  0  4  5  6 

6 

-9  3  -3  0  -1 

9 

.-4  0-2-1  5  . 

*  >  0 

.4. 

2.  Add  the  constraint; 


— 5*i  —  8*a  —  5*8  —  6*4  —  7*5  >  — 23 
and  re-solve  using  the  previous  solution  as  the  starting  point. 

3.  Add  a  column  corresponding  to  a  new  variable,  z6.  Let  this  variable  have  a 
coefficient  of  1.0  in  the  first  constraint,  and  a  cost  coefficient  of  -30.0.  Let 
all  other  coefficients  be  zero  for  this  variable.  Re-solve,  again  starting  from 
the  previous  solution. 


Here  is  a  listing  of  MATMOD  corresponding  to  the  above  example.  This  is  followed 
by  an  appropriate  SPECS  file  and  MPS  file. 


SUBROUTINE  MATMOD t  NCYCLE .CNVTOL , FINISH , 

1  M»N»NR0WS»NC0LS,NE»NP1» 

2  A,BL,BU»HA,KA, 101,102, 

3  PI,XL,XS,Z,MAXZ,LFREE  ) 

IMPLICIT  REAL#8(C-G,0-Z) 

LOGICAL  FINISH 
DIMENSION  ACNE) ,BL( N ) »BU( N ) 

INTEGERS  HACNE) 

INTEGER  KA(NP1),I01(N),I02(N) 

REAL*8  PI(NR0HS),XL(NR0HS),XS(NC0LS),Z(MAXZ) 

EXAMPLE  OF  USER -WRITTEN  SUBROUTINE  MATM00. 

THE  FOLLOWING  4  COMMON  BLOCKS  ARE  USED  WITHIN  MINOS 
THEY  SHOULD  NOT  BE  OVERWRITTEN,  WITH  THE  POSSIBLE 
EXCEPTION  OF  AIJTOL  IN  COMMON  BLOCK  MPSCOM. 

COMMON  /FXCOM  /  FX,FXNONL»SINF,MTOBJ,MINIMZ,NINF,IOBJ.NPROB 

COMMON  /IOCOMM/  IREAO.IPRINT 

COMMON  /LPCOM  /  KRHS.NSl.MAXR.IERR.IDEBUG.LPRINT 

COMMON  /MPSCOM/  AIJTOL, BSTRUCC 2 ),HINMAX,MLST,MER, 

I  NAMEC 2 ) .MOBJC C ) ,HRHS( C ) ,HRNB( 2 ) ,HBND( 2 ) 
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c 

c 

c 


c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 


c 

c 

c 

c 

c 


c 

c 

c 

c 

c 

c 

c 


c 

c 

c 


c 

c 

c 

c 


c 

c 

c 


c 

c 

c 

c 


DECURE  LOCAL  STORAGE. 

REAL  AVALC6 ) »ACOL( IS ) 

DATA  NAME  A *  NAMEB/4HR0W *  4HUM0  7/ 

TEST  FOR  ERROR  CONDITION  WITHIN  MINOS. 

IF  (IERR.NE.0)  STOP 

NOTE  THAT  ON  THE  FIRST  ENTRY  (BEFORE  A  PROBLEM  IS  SOLVED) 

WHEN  NCYCLE  «  1*  ME  RETURN  IMMEDIATELY. 

ALSO  NOTE  THAT  THE  PROBLEM  HAS  BEEN  READ  BY  THIS  TIME*  SO 
WE  CAN  RESET  AIJTOL  TO  A  POSITIVE  VALUE  TO  CONSERVE  STORAGE 
UTER  WHEN  ADDINS  COLUMNS. 

AIJTOL  =  .00001 
IF  (NCYCLE  .EQ.  I)  RETURN 
IF  (NCYCLE  .EQ.  3)  60  TO  150 

ON  THE  SECONO  CALL  TO  MATHOO  HE  ADD  A  CONSTRAINT  BY  MODIFYING 
SOME  CURRENTLY  EXISTING  ZERO  MATRIX  ELEMENTS*  ANO  BY  MOOIFYXN6 
THE  BOUND  ON  THE  SUCK  VARIABLE  CORRESPONDING  TO  THAT  ROM. 

AVAL(l)  =  -5.0 
AVALC  2 )  =  -6.0 
AVAL( 3)  =  -5.0 
AVAL(4)  *  -6.0 
AVAL( 5 )  *  -7,0 
AVAU6)  *  -23.0 

NOW  LET  NMSRCH  FIND  THE  INDEX  FOR  THE  ROM  NAMED  R0MNUM07. 

SINCE  THE  ROM  NAMES  FOLLOW  THE  COLUMN  NAMES  AND  RHS  NAME* 

ME  MUST  SUBTRACT  ONE  PLUS  THE  NUMBER  OF  VARIABLES  C*KRHS>  FROM 
J FOUND  TO  GET  THE  ROM  INDEX. 

ISTART  =  I 

CALL  NMSRCH( N* 101 > 102 » NAME A  *  NAMED  * 1  *  NOTFND » 

1  1*1*N*ISTART > JFOUND ) 

CHECK  TO  MAKE  SURE  WE  FOUND  THE  NAME. 

IF  ( JFOUND. EQ.O)  GO  TO  125 
JFOUND  =  JFOUND  -  KRHS 
DO  100  Jsl»5 

CALL  MODELM(  A* JFOUND* J,AVAL(J ) *HA,KA*M*N,NE*NP1  > 

100  CONTINUE 

CALL  MOOELM(  A* JFOUND *KRHS* AVALC 6 )*HA,KA,M*N*NE,NP1  ) 

COMPUTE  THE  INDEX  OF  THE  SUCK  VARIABLE  CORRESPONDING 
TO  ROW  JFOUND. 

JFOUND  3  JFOUND  ♦  KRHS 
BVAL  »  0.0 

CALL  MOOBNOC  JFOUND *BVAL,BL*BU*N  ) 

RETURN 

NAME  NOT  FOUND. 

125  WRITE( IPRINT *1000 )  NAMEA*NAMEB 
IERRO  a  IERRO  ♦  1 
RETURN 

ON  THE  THIRD  CALL  TO  MATMOD  (NCYCLE  *  3)  A  COLUMN  IS  ADDED  TO 
THE  MATRIX  USING  THE  UST  OF  THE  NEW  SUBROUTINES*  MKCOL. 

150  DO  200  I«2*M 

ACOUI)  «  0.0 
200  CONTINUE 

ACOL(l)  «  1.0 


!• 
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c 

C  use  XOBJ  FROM  COMMON  BLOCK  fxcom  to  find  the  objective  row. 
c 

ACOL(XOBJ)  «  -50.0 
LEKCOL  «  h 

CALL  MKCOLt  A»ACOL»BLiBU»HA»KA»LENCOL»N»NE»NPl  ) 

RETURN 

C 

1000  FORMAT  ( 1X.27HXXXX  VARIABLE  OR  ROW  INDEX  »2A4»UH  NOT  FOUND.) 
C  ENO  OF  MATMOO 
END 


SPECS  file: 

BEGIN  CLP 

OBJECTIVE  OBJECTZV 
ROUS  10 

COLUMNS  30 

ELEMENTS  250 

SOLUTION  IF  OPTIMAL 
AXJTOL  -0.0001 

CYCLE  PRINT  1 

CYCLE  TOLERANCE  0.001 
CYCLE  LIMIT  3 

PHANTOM  COLUMNS  10 
PHANTOM  ELEMENTS  100 

END 


MPS  file: 

NAME 

CLP 

ROWS 

L  ROWNUMOl 

L  ROWNUMOS 

L  ROWNUM03 

L  ROKNUM04 

L  ROWNUM05 

L  ROWNUMOS 

N  R0iZNUM07 

N  OBJECTIV 

COLUMNS 

XI 

ROWNUMOl 

XI 

ROWNUM03 

XI 

R0WNUM05 

XI 

ROWMUM07 

X2 

ROWNUMOl 

X2 

ROWNUMOl 

X2 

ROWNUM07 

X3 

ROWNUMOl 

X3 

ROWNUM03 

X3 

ROWNUMOS 

X3 

ROWNUM07 

X4 

ROWNUMOl 

X4 

R0WNUM04 

X4 

R0WNUM07 

X5 

ROWNUMOl 

X5 

R0WNUM04 

X5 

R0UNUM04 

X5 

OBJECTZV 

RHS 

RHS00001 

ROMJMOl 

RHS00001 

ROWNUMOl 

RHS00001 

ROWNUMOl 

RHS00001 

R0WNUM04 

RHS00001 

ROWNUMOS 

RHS00001 

ROWNUMOS 

RHS00001 

ROWNUM07 

ENOATA 

1.0 

ROWNUMOS 

S.O 

2.0 

ROWNUM04 

-3.0 

-9.0 

ROWNUMOS 

-4.0 

0.0 

OBJECTIV 

-5.0 

1.0 

ROWNUMOS 

S.O 

2.0 

ROWNUMOS 

3.0 

0.0 

OBJECTIV 

-6.0 

1.0 

ROWNUMOS 

-1.0 

3.0 

R0NNUM04 

4.0 

-3.0 

ROWNUMOS 

-S.O 

0.0 

OBJECTIV 

-S.O 

1.0 

ROWNUMOS 

-3.0 

s.o 

ROWNUMOS 

-1.0 

0.0 

OBJECTZV 

-S.O 

1.0 

ROWNUMOS 

S.O 

4.0 

ROIMJMOS 

-1.0 

S.O 

ROWNUM07 

0.0 

-7 
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7.  ON  MODIFYING  NONLINEAR  PROGRAMS 

To  this  point  the  examples  and  modules  have  been  aimed  at  modifying  linear 
problems.  The  generalization  to  nonlinear  problems  is  straightforward. 

To  communicate  with  CALCFG  or  CALCON,  declare  a  new  common  block  (with 
a  non-reserved  name)  and  append  it  to  the  declarations  in  MATMOD,  CALCFG  and 
CALCON.  If  it  is  determined  to  be  advantageous  to  modify  the  nonlinear  functions, 
MATMOD  can  pass  information  to  CALCFG  and  CALCON  via  the  new  common  block. 

In  some  cases,  the  nonlinear  functions  could  be  modified  directly  in  CALCFG 
or  CALCON,  as  follows.  If  the  SPECS  file  uses  both  of  the  specifications: 

CYCLE  LIMIT  I 

CALL  FUNCTIONS  WHEN  OPTIMAL 

where  I  is  some  positive  integer,  then  a  special  call  to  CALCFG  and  CALCON  will 
occur  with  the  parameter  value  NSTATE  =  2,  whenever  a  subproblem  Pk  has 
been  solved  to  optimality.  (Note  that  this  special  call  will  also  occur  after  P  .) 
Some  information  in  an  appropriate  common  block  could  then  be  altered.  These 
modifications  may  be  based  on  the  values  for  the  nonlinear  variables  (held  in 
array  X),  but  the  dual  multipliers  and  strictly  linear  variables  are  inaccessible  to 
CALCFG  and  CALCON.  If  all  problem  modifications  for  the  sequence  { Pk }  can  be 
performed  in  CALCFG  and  CALCON,  then  standard  MINOS/AUGMENTED  may 
be  used  as  is.  (The  printing  parameters  documented  in  this  paper  will  be  ignored 
if  standard  MINOS/AUGMENTED  is  used.) 

8.  SUMMARY 

The  modules  provided  are  designed  for  use  with  the  nonlinear  programming 
system  MINOS/AUGMENTED  to  ease  the  difficulty  of  efficiently  implementing 
algorithms  requiring  the  solution  of  sequences  of  similar  mathematical  programs. 
Using  this  system,  all  problem  modifications  can  be  performed  in-core;  hence, 
overhead  for  disk  input/output  is  kept  to  a  minimum.  The  modules  described 
here  make  learning  the  specific  data  structures  used  in  MINOS/AUGMENTED 
unnecessary. 

In  the  case  of  nonlinear  programs,  information  can  be  saved  from  problem 
Pk.  MINOS/ AUGMENTED  can  begin  to  solve  the  mathematical  program  P*+1 
using  the  reduced  Hessian  approximation,  Lagrange  multiplier  estimates,  basis 
and  superbasis  from  Pk.  This  flying  start  feature  will  usually  result  in  significant 
computational  savings. 

This  package  was  created  to  facilitate  research  in  the  field  of  solving  for 
economic  equilibria  via  optimization  methods.  Restrictions  on  the  types  of 
modifications  of  the  mathematical  programs  in  the  sequence  have  been  kept  to 
a  minimum  to  provide  greater  flexibility  to  users.  Hence,  this  system  could  be 


AekaawladgtmaaU  IS 

useful  for  research  in  other  areas  such  as  integer  programming  and  very  large 
scale  linear  programming. 
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APPENDIX-ADDITIONAL  COMMON  INFORMATION 

One  of  the  common  blocks  in  MINOS/ AUGMENTED  contains  items  relevant 
to  solving  sequences  of  problems.  This  common  block  contains  the  control 
parameters  for  cycling  and  should  not  be  overwritten.  The  parameters  held 
therein  are  defined  below. 


Declaration: 

COMMON  /CYCLCM/  CNVTOL . IERRO , I FREE , MAXCY , NEPHNT , NPHANT , NPRINT 

Variables: 

CNVTOL  See  parameter  list  for  MATMOD. 

IERRO  Error  flag  for  inconsistencies  in  MATMOD. 

I  FREE  Marks  the  beginning  of  the  currently  unused  phantom  column  space. 

MAXCY  The  maximum  number  of  mathematical  programs  to  be  solved.  The 
value  of  this  parameter  is  defined  by  the  CYCLE  LIMIT. 

NEPHNT  The  number  of  nonzero  elements  allowed  for  in  the  phantom  column 
space.  The  value  of  this  parameter  is  defined  by  the  PHANTOM  ELEMENTS 
keyword. 

NPHANT  The  number  of  PHANTOM  COLUMNS  specified  in  the  SPECS  file. 

NPRINT  The  value  of  NPRINT  is  specified  by  CYCLE  PRINT  in  the  SPECS  file. 
The  solutions  for  problems  NPRINT  though  pMAXCY 

printed. 


\ 
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INDEX 

Adding  constraints  to  Pk,  1 

AIJ  TOLERANCE  (See  AIJTOL),  3,  5,  6 

AIJTOL,  3,  5,  6 

Bounds  for  logical  variables,  6 
infinite,  6 

CALCFG,  12 
CALCON,  12 

CALL  FUNCTIONS  VEEN  OPTIMAL,  12 
CNVTOL,  parameter  to  MATMOD,  3-4 
common  variable,  13 
Column  ordering,  8 
Common  blocks,  4,  6,  8,  12,  13 
Constraints,  adding  to  Pk,  1 
Convergence  tolerance,  3-4 
CYCLCM  common  block,  13 
CYCLE  LIMIT,  2,  12 
CYCLE  PRINT,  2 
CYCLE  TOLERANCE,  2 

Default  values  for  SPECS  file  keywords,  2-3 

Error  conditions  within  MIN  OS/  AUGMENTED,  4 
within  MATMOD,  5,  6,  7 
Example,  8-11 

FINISH,  parameter  to  MATMOD,  3-4 
Flying  start  option,  5,  12 
Free  row,  1 

Indexing,  8 
Infinite  bounds,  6 
IOBJ,  8 

XRH8,  8 

MATMOD,  3 
MINOS,  5 
MKCOL,  5 
MODBND,  6 
MODELM,  7 

Modifications  of  a  problem  Pk,  1 
MPS  file,  1 


INDEX 


IT 


■CYCLE,  parameter  to  MATKOD,  3-4 
parameter  to  DRIVER,  5 
■KERCH,  8 

Nonlinear  programs,  12 

PHANTOM  COLUMXS,  2,  3,  5 

PHANTOM  ELEMENTS,  2, 3 

Problem  form  solved  by  this  system,  1 

Row  ordering,  8 

SPECS  file,  2 
example,  11 

Tolerance,  for  convergence  of  user’s  algorithm,  3-4 
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ABSTRACT 

The  modules  documented  herein  are  designed  for  use  -with  the  nonlinear 
programming  system  MINOS/AUGMENTED  when  implementing  algorithms  re¬ 
quiring  the  solution  of  sequences  of  similar  mathematical  programs.  Large-scale 
constrained  mathematical  programming  requires  the  use  of  special  data  struc¬ 
tures  which  make  in-core  problem  modification  difficult.  These  modules  allow 
in-core  modification  of  nonlinear  programs  without  knowledge  of  the  specialised 
data  structures  used  in  MINOS/AUGMENTED. 

The  modifications  addressed  by  these  modules  are:  modification  of  elements 
in  the  constraint  matrix,  linear  objective  or  right  hand  side;  modification  of 
bounds  on  individual  variables;  modification  of  the  nonlinear  functions;  and 
appending  columns  to  the  constraint  matrix.  The  user  specifies  the  flow  and 
nature  of  problem  modifications  via  a  Fortran  subroutine.  A  simple  example  of 
the  use  of  each  of  the  modules  is  presented. 

This  manual  supplements  Reports  SOL  77-9  and  SOL  80-14,  the  MINOS 
User’s  Guide  and  the  MINOS/AUGMENTED  User’s  Manual. 


